home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / IDLIncludes / NameRegistry.idl < prev    next >
Text File  |  1996-05-01  |  20KB  |  597 lines
  1. /*
  2.      File:        NameRegistry.idl
  3.  
  4.      Contains:    NameRegistry Interfaces
  5.  
  6.      Version:    Technology:    System 8
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __NAMEREGISTRY_IDL__
  19. #define __NAMEREGISTRY_IDL__
  20.  
  21. #include <somobj.idl>
  22. #include <somcls.idl>
  23.  
  24. #ifndef __TYPES_IDL__
  25. #include <Types.idl>
  26. #endif
  27.  
  28. #ifdef __SOMIDL__
  29.  
  30. #if FOR_SYSTEM7_AND_SYSTEM8_PREEMPTIVE
  31. /*
  32.  These definitions apply to both the System7 and System8 interfaces
  33.  RegEntryRef:    The Global Entry Reference
  34. */
  35. typedef SOMLargeStruct            RegEntryRef;                /* Derived from a struct of 16 bytes in size */
  36.  
  37. typedef OpaquePtr                RegPropertyNameBuf;            /* Substituted OpaquePtr for array of char of size 32 */
  38.  
  39. #endif
  40. #if FOR_SYSTEM8_PREEMPTIVE
  41. /*
  42. ------------------------------------------------------------------------------------
  43. Name Registry Interface for System 8
  44. ------------------------------------------------------------------------------------
  45. */
  46. /*
  47. ------------------------------------------------------------------------------------
  48.  Foundation Types
  49. ------------------------------------------------------------------------------------
  50. */
  51. /* Entry Name Definitions (Entry Names are C-Strings)*/
  52. /* length of RegEntryNameBuf = kRegMaxEntryNameLength +1*/
  53. typedef OpaquePtr                RegEntryNameBuf;            /* Substituted OpaquePtr for array of char of size 48 */
  54.  
  55. /* Create Entry Options*/
  56. typedef OptionBits                RegCreateEntryOptions;
  57.  
  58. /* use "kNilOptions" for no options*/
  59. /* Delete Entry Options*/
  60. typedef OptionBits                RegDeleteEntryOptions;
  61.  
  62. /* use "kNilOptions" for no options*/
  63. /* Entry Iterator*/
  64. typedef OpaquePtr                RegEntryIterator;
  65.  
  66. /* Entry Iterator Options*/
  67. typedef OptionBits                RegEntryIteratorOptions;
  68.  
  69. /* use "kNilOptions" for no options*/
  70. /*
  71.  Property Instances
  72.  An instance value for a property is assigned by the Name Registry when the
  73.  instance is created.  This value is used to distinguish this instance from any
  74.  other instances of the property.  Instance values are unique and persistent for
  75.  the life of the property. Thus, clients can obtain a reference to a property (name
  76.  and instance value) and use that reference until the property is deleted or the
  77.  system is restarted.  At restart, new instance values are assigned to all
  78.  properties, including any restored persistent properties.
  79. */
  80. typedef UInt32                    RegPropertyInstance;
  81.  
  82. /* Create Property Options*/
  83. typedef OptionBits                RegCreatePropertyOptions;
  84.  
  85. /* use "kNilOptions" for no options*/
  86. /* Property Iterator*/
  87. typedef OpaquePtr                RegPropertyIterator;
  88.  
  89. /* Transaction Reference*/
  90. typedef OpaquePtr                RegTransaction;
  91.  
  92. /* Nil Transaction Reference*/
  93. /*
  94. ------------------------------------------------------------------------------------
  95.  Name Registry Calls
  96. ------------------------------------------------------------------------------------
  97. */
  98. /*
  99. ------------------------------------------------------------------------------------
  100.  EntryRef Handling
  101. ------------------------------------------------------------------------------------
  102. */
  103. /* Compare two EntryRef's for equality. */
  104. /*
  105. ------------------------------------------------------------------------------------
  106.  Adding and Deleting Entries
  107. ------------------------------------------------------------------------------------
  108. */
  109. /*
  110.  Create an Entry
  111.  If (parentEntry) is NULL, the path name is assumed to be an absolute path name
  112.  rooted to the anonymous, unnamed root.  
  113.  Note, RegCreateEntry only creates a single entry, the one at the end of the path.
  114.  Thus, all parent entries along the path to the new entry (ancestors) must already
  115.  exist.
  116. */
  117. /*
  118.  Delete an Entry or Subtree
  119.  RegDeleteEntry can be used to delete a single entry or a complete subtree.
  120.  To delete a subtree, set the RegDeleteEmbedded option.
  121.  All properties for deleted entries are also deleted.
  122. */
  123. /*
  124. ------------------------------------------------------------------------------------
  125.  LookUp Entry by Name
  126. ------------------------------------------------------------------------------------
  127. */
  128. /*
  129.  Lookup Entry
  130.  Locates an entry given a specified subroot (searchPointRef) and path name.  If the
  131.  searchPointRef pointer is NULL, the path name is assumed to be an absolute path
  132.  name rooted to the root of the Registry.
  133. */
  134. /*
  135. ------------------------------------------------------------------------------------
  136. Get Entry Name and Parent
  137. ------------------------------------------------------------------------------------
  138. */
  139. /*
  140.  Retrieve the name component for the specified entry, and return the EntryRef for
  141.  the parent entry.
  142. */
  143. /*
  144. ------------------------------------------------------------------------------------
  145. Get Path Name
  146. ------------------------------------------------------------------------------------
  147. */
  148. /*
  149.  These are utility routines to turn an Entry ID back into a name string.
  150.  Get Entry Path Size
  151.  Note, path size is returned in bytes for C-String paths
  152. */
  153. /* Get Path Name*/
  154. /*
  155. ------------------------------------------------------------------------------------
  156.  Entry Iteration
  157. ------------------------------------------------------------------------------------
  158. */
  159. /*
  160.  An Entry Iterator maintains three variables that are of interest to clients.
  161.  First is an "OutermostScope" which defines the outer boundry of the iteration.
  162.  This is defined by the starting entry and includes that entry plus all of it's
  163.  embedded entries. Second is a "currentScope" which is the entry the iterator is
  164.  currently in. And third is a "currentPosition" which is the last entry returned
  165.  during an iteration.
  166.  Create Entry Iterator
  167.  Create the iterator structure. The outermostScope and currentScope of the iterator
  168.  are set to "startEntry".  If "startEntry" = NULL, the outermostScope and
  169.  currentScope are set to the root entry.  The currentPosition for the iterator is
  170.  set to "nil".
  171.  If propertyName != Null, propertyName, propertyValue, and propertySize are used
  172.  to filter the entries returned during an iteration.  If propertyName == Null, all
  173.  entries are returned.
  174. */
  175. /* Dispose Entry Iterator*/
  176. /*
  177.  Enter Child Entry
  178.  Move an Entry Iterator into the scope of a specified child entry.  The
  179.  currentScope of the iterator is set to the entry specified in "childEntry".  If
  180.  "childEntry" is nil, the currentScope is set to the entry specified by the
  181.  currentPosition of the iterator.
  182.  Note RegEnterEntry cannot be used if the "kRegIterateEmbeddedEntries" option was
  183.  set when the iterator was created. 
  184. */
  185. /*
  186.  Exit to Parent Entry
  187.  Move an Entry Iterator out of the current entry back into the scope of it's parent
  188.  entry. The currentPosition of the iterator is reset to the current entry (the
  189.  previous currentScope), so the next iteration call will continue where it left off.
  190.  This position is returned in parameter "currentPosition".
  191.  Note RegExitEntry cannot be used if the "kRegIterateEmbeddedEntries" option was
  192.  set when the iterator was created. 
  193. */
  194. /*
  195.  Iterate Entries 
  196.  Iterate and return entries contained within the entry defined by the current
  197.  scope of the iterator. If kRegIterateEmbeddedEntries option was specified when the
  198.  iterator was created, all embedded entries will be included in the iteration.  If a
  199.  property selection (name , value, and size) was specified when the iterator was
  200.  created, the only entries having a matching property are returned.  Entries are
  201.  returned one at a time. When OSStatus == nrIterationDone, all entries have been exhausted, and the
  202.  value of nextEntry will be Nil. If changed == true, one or more changes (entry
  203.  create or delete) occured since the last interation call.
  204. */
  205. /*
  206.  Restart Entry Iteration
  207.  Restart an iteration within the current scope.  The iterator is reset such that
  208.  iteration of the contents of the currentScope entry can be restarted. The
  209.  outermostScope and currentScope of the iterator are unchanged. The currentPosition
  210.  for the iterator is set to "nil".
  211. */
  212. /*
  213. ------------------------------------------------------------------------------------
  214.  Adding and Deleting Properties
  215. ------------------------------------------------------------------------------------
  216. */
  217. /*
  218.  Create Property
  219.  A  single instance property is created by default. To create a multiple-instance
  220.  property set the kRegMultiInstanceProperty option. The next instance of the
  221.  property will be created and the instance value will be returned in
  222.  propertyInstance.
  223. */
  224. /*
  225.  Delete Property
  226.  To delete a property the desired property instance(s) must be explicitly
  227.  identified. To delete a single instance property set propertyInstance to
  228.  kRegNilPropertyInstance.  To delete all instances of a multi-instance property, set
  229.  propertyInstance to kRegAllPropertyInstances.  Otherwise, propertyInstance must
  230.  be set to a valid instance value.
  231. */
  232. /*
  233. ------------------------------------------------------------------------------------
  234.  Get/Set Property Values
  235. ------------------------------------------------------------------------------------
  236. */
  237. /*
  238.  Get/Set the value of the specified property for the specified entry.  To get, get
  239.  size, and set property values the desired property instance must be explicitly
  240.  identified.  For single instance properites propertyInstance must  be set to
  241.  kRegNilPropertyInstance.  Otherwise, propertyInstance must be set to a valid
  242.  instance value.
  243.  Get Property size
  244. */
  245. /* Get Property*/
  246. /* Set Property*/
  247. /*
  248. ------------------------------------------------------------------------------------
  249.  Iterating Properties
  250. ------------------------------------------------------------------------------------
  251. */
  252. /*
  253.  Create Property Iterator
  254.  Create the property iterator structure. The target entry is defined by entryRef.
  255.  If a propertyName is specified, only property instances having the specified name
  256.  are returned. If propertyName == nil, all properties are returned.
  257. */
  258. /* Dispose Property Iterator*/
  259. /*
  260.  Iterate Properites
  261.  Iterate and return properties for given entry.  If a propertyName was specified
  262.  when the iterator was created, then only property instances for that name are
  263.  returned. Otherwise, all properties are returned.  The return value in
  264.  propertyInstance will be kRegNilPropertyInstance if the property is single
  265.  instance.  Else it will contain the instance value for the property. If
  266.  changed == true, one or more changes (property creates or deletes) occured since the
  267.  last iterate call.  When OSStatus == nrIterationDone, all properties have been exhausted.
  268. */
  269. /*
  270.  Restart Property Iteration
  271.  Used to re-iterate over a list of properties.  The Property Iterator is reset to
  272.  the beginning of the list of properties for an entry.
  273. */
  274. /*
  275. ------------------------------------------------------------------------------------
  276.  Transaction-control calls
  277. ------------------------------------------------------------------------------------
  278. */
  279. /*
  280.  Begin Transaction
  281.  Marks the beginning of a sequence of Name Registry calls that compose a Registry
  282.  transaction.  An internal data structure for the transaction is created and a
  283.  reference to the transaction is returned in "tranasaction". This reference must be
  284.  used with all subsequence Name Registry calls pertaining to the transaction. The
  285.  transaction reference must be disposed using a RegCommitTransaction or
  286.  RegAbortTranscation call.    
  287. */
  288. /*
  289.  Commit Transaction
  290.  Commits the changes made to the registry for a sepecified transaction. All changes
  291.  (entry create/delete, property create/delete, and  property value update) made for
  292.  the transaction are atomically integrated into the Registry.  If result ==
  293.  nrTransactionAborted, there was a conflict with changes from some other transaction,
  294.  and this transaction was aborted, i.e., no changes for this transaction were made.
  295.  In this case the transaction should be repeated.
  296.  Note that RegCommitTransaction always disposes the transcation reference
  297.  independant of the outcome of the transaction.  So to repeat a transaaction you
  298.  must start over with a RegBeginTransaction call.
  299. */
  300. /*
  301.  Abort Transaction
  302.  Aborts the changes made to the registry for a sepecified transaction. All changes
  303.  (entry create/delete, property create/delete, and  property value update) made for
  304.  the transaction are disgarded.  
  305.  RegAbortTransaction also disposes of the transcation reference.
  306. */
  307. #endif
  308. #if FOR_SYSTEM7_AND_SYSTEM8_DEPRECATED
  309. /*
  310. ------------------------------------------------------------------------------------
  311.     Name Registry Interface for PowerSurge 1.0.2
  312. ------------------------------------------------------------------------------------
  313. */
  314. /*
  315.  * Name Registry - API for device driver name registration
  316.  *
  317.  * This interface provides access to the namespace used
  318.  * by device drivers.  The data structures and entry points
  319.  * are specialized and simplified for device driver use.
  320. */
  321. /*
  322.  //////////////////////////////////////////////////////////////////////////////
  323. //
  324. // Data Structures
  325. //
  326. */
  327. /*
  328.  //////////////////////////////////////////////////////////////////////////////
  329. // 
  330. // Foundation Types
  331. //
  332. */
  333. /* Value of a property */
  334. typedef OpaquePtr                RegPropertyValue;            /* Substituted OpaquePtr for ``void*'' */
  335.  
  336. /* Length of property value */
  337. typedef UInt32                    RegPropertyValueSize;
  338.  
  339. /*
  340.  //////////////////////////////////////////////////////////////////////////////
  341. // 
  342. // RegEntryID    :    The Global x-Namespace Entry Identifier
  343. //
  344. */
  345. /* RegEntryID:    The Global Entry ID*/
  346. typedef RegEntryRef                RegEntryID;
  347.  
  348. typedef OpaquePtr                RegEntryIDPtr;                /* Substituted OpaquePtr for ``RegEntryID*'' */
  349.  
  350. /*
  351.  //////////////////////////////////////////////////////////////////////////////
  352. //
  353. // Root Entry Name Definitions    (Applies to all Names in the RootNameSpace)
  354. //
  355. //    * Names are a colon-separated list of name components.  Name components
  356. //      may not themselves contain colons.  
  357. //    * Names are presented as null-terminated ASCII character strings.
  358. //    * Names follow similar parsing rules to Apple file system absolute
  359. //      and relative paths.  However the '::' parent directory syntax is
  360. //      not currently supported.
  361. */
  362. /* Max length of Entry Name */
  363. /* Entry Names are single byte ASCII */
  364. typedef char                    RegCStrEntryName;
  365.  
  366. typedef OpaquePtr                RegCStrEntryNamePtr;        /* Substituted OpaquePtr for ``char*'' */
  367.  
  368. /* length of RegCStrEntryNameBuf =  kRegCStrMaxEntryNameLength+1*/
  369. typedef OpaquePtr                RegCStrEntryNameBuf;        /* Substituted OpaquePtr for array of char of size 48 */
  370.  
  371. typedef char                    RegCStrPathName;
  372.  
  373. typedef UInt32                    RegPathNameSize;
  374.  
  375. /*
  376.  //////////////////////////////////////////////////////////////////////////////
  377. //
  378. // Property Name and ID Definitions
  379. //    (Applies to all Properties Regardless of NameSpace)
  380. */
  381. typedef char                    RegPropertyName;
  382.  
  383. typedef OpaquePtr                RegPropertyNamePtr;            /* Substituted OpaquePtr for ``char*'' */
  384.  
  385. /*
  386.  //////////////////////////////////////////////////////////////////////////////
  387. //
  388. // Iteration Operations
  389. //
  390. //    These specify direction when traversing the name relationships
  391. */
  392. typedef UInt32                    RegIterationOp;
  393.  
  394. typedef RegIterationOp            RegEntryIterationOp;
  395.  
  396. /*
  397.  //////////////////////////////////////////////////////////////////////////////
  398. //
  399. // Name Entry and Property Modifiers
  400. //
  401.  
  402. //
  403. // Modifiers describe special characteristics of names
  404. // and properties.  Modifiers might be supported for
  405. // some names and not others.
  406. // 
  407. // Device Drivers should not rely on functionality
  408. // specified as a modifier.
  409. */
  410. typedef UInt32                    RegModifiers;
  411.  
  412. typedef RegModifiers            RegEntryModifiers;
  413.  
  414. typedef RegModifiers            RegPropertyModifiers;
  415.  
  416. /* Universal Property Modifiers */
  417. /*
  418.  ///////////////////////
  419. //
  420. // The Registry API
  421. //
  422. /////////////////////// 
  423. */
  424. /*
  425.  ///////////////////////
  426. //
  427. // Entry Management
  428. //
  429. /////////////////////// 
  430. */
  431. /*
  432. -------------------------------
  433.  * EntryID handling
  434. */
  435. /*
  436.  * Initialize an EntryID to a known invalid state
  437.  *   note: invalid != uninitialized
  438. */
  439. /*
  440.  * Compare EntryID's for equality or if invalid
  441.  *
  442.  * If a NULL value is given for either id1 or id2, the other id 
  443.  * is compared with an invalid ID.  If both are NULL, the id's 
  444.  * are consided equal (result = true). 
  445. */
  446. /*
  447.  * Copy an EntryID
  448. */
  449. /*
  450.  * Free an ID so it can be reused.
  451. */
  452. /*
  453. -------------------------------
  454.  * Adding and removing entries
  455.  *
  456.  * If (parentEntry) is NULL, the name is assumed
  457.  * to be a rooted path. It is rooted to an anonymous, unnamed root.
  458. */
  459. /*
  460. ---------------------------
  461.  * Traversing the namespace
  462.  *
  463.  * To support arbitrary namespace implementations in the future,
  464.  * I have hidden the form that the place pointer takes.  The previous
  465.  * interface exposed the place pointer by specifying it as a
  466.  * RegEntryID.
  467.  *
  468.  * I have also removed any notion of returning the entries
  469.  * in a particular order, because an implementation might
  470.  * return the names in semi-random order.  Many name service
  471.  * implementations will store the names in a hashed lookup
  472.  * table.
  473.  *
  474.  * Writing code to traverse some set of names consists of
  475.  * a call to begin the iteration, the iteration loop, and
  476.  * a call to end the iteration.  The begin call initializes
  477.  * the iteration cookie data structure.  The call to end the 
  478.  * iteration should be called even in the case of error so 
  479.  * that allocated data structures can be freed.
  480.  *
  481.  *    Create(...)
  482.  *    do {
  483.  *        Iterate(...);
  484.  *    } while (!done);
  485.  *    Dispose(...);
  486.  *
  487.  * This is the basic code structure for callers of the iteration
  488.  * interface.
  489. */
  490. typedef OpaquePtr                RegEntryIter;
  491.  
  492. /*
  493.  * create/dispose the iterator structure
  494.  *   defaults to root with relationship = kRegIterDescendants
  495. */
  496. /*
  497.  * set Entry Iterator to specified entry
  498. */
  499. /*
  500.  * Return each value of the iteration
  501.  *
  502.  * return entries related to the current entry
  503.  * with the specified relationship
  504. */
  505. /*
  506.  * return entries with the specified property
  507.  *
  508.  * A NULL RegPropertyValue pointer will return an
  509.  * entry with the property containing any value.
  510. */
  511. /*
  512. --------------------------------
  513.  * Find a name in the namespace
  514.  *
  515.  * This is the fast lookup mechanism.
  516.  * NOTE:  A reverse lookup mechanism
  517.  *      has not been provided because
  518.  *        some name services may not
  519.  *        provide a fast, general reverse
  520.  *        lookup.
  521. */
  522. /*
  523. ---------------------------------------------
  524.  * Convert an entry to a rooted name string
  525.  *
  526.  * A utility routine to turn an Entry ID
  527.  * back into a name string.
  528. */
  529. /*
  530.  * Parse a path name.
  531.  *
  532.  * Retrieve the last component of the path, and
  533.  * return a spec for the parent.
  534. */
  535. /*
  536.  //////////////////////////////////////////////////////
  537. //
  538. // Property Management
  539. //
  540. ////////////////////////////////////////////////////// 
  541. */
  542. /*
  543. -------------------------------
  544.  * Adding and removing properties
  545. */
  546. /*
  547. ---------------------------
  548.  * Traversing the Properties of a name
  549.  *
  550. */
  551. typedef OpaquePtr                RegPropertyIter;
  552.  
  553. /*
  554.  * Get the value of the specified property for the specified entry.
  555.  *
  556. */
  557. /*
  558.  * (*propertySize) is the maximum size of the value returned in the buffer
  559.  * pointed to by (propertyValue).  Upon return, (*propertySize) is the size of the
  560.  * value returned.
  561. */
  562. /*
  563.  //////////////////////////////////////////////////////
  564. //
  565. // Modibute (err, I mean Modifier) Management
  566. //
  567. ////////////////////////////////////////////////////// 
  568. */
  569. /*
  570.  * Modifiers describe special characteristics of names
  571.  * and properties.  Modifiers might be supported for
  572.  * some names and not others.
  573.  * 
  574.  * Device Drivers should not rely on functionality
  575.  * specified as a modifier.  These interfaces
  576.  * are for use in writing Experts.
  577. */
  578. /*
  579.  * Get and Set operators for entry modifiers
  580. */
  581. /*
  582.  * Get and Set operators for property modifiers
  583. */
  584. /*
  585.  * Iterator operator for entry modifier search
  586. */
  587. /*
  588.  * Iterator operator for entries with matching 
  589.  * property modifiers
  590. */
  591. #endif
  592.  
  593. #endif /* __SOMIDL__ */
  594.  
  595. #endif /* __NAMEREGISTRY_IDL__ */
  596.  
  597.